## 🚩 FLAG REFERENCE & ERROR PATTERNS

### 📦 `options` Object Flags

#### `options.draft`
- ✅ **Set by:** `execute()` from operation config
- ✅ **Default:** `false` (from `coworker._config.operations[operation].draft`)
- ❌ **Error:** Calling `save()` when `draft=false` → "Document not in draft mode"
- ❌ **Error:** `autoSave()` silently exits if `draft=false`

#### `options.skipController`
- ✅ **Set by:** User/caller
- ✅ **Effect:** Bypasses entire controller, calls handler directly
- ⚠️ **Risk:** No validation, no schema fetch, no draft support

#### `options.skipSchema`
- ✅ **Set by:** User/caller  
- ✅ **Effect:** Prevents schema fetch even if `requiresSchema=true`
- ⚠️ **Risk:** Validation may fail without schema

#### `options.skipValidation`
- ✅ **Set by:** User/caller
- ✅ **Effect:** Bypasses `_validate()` for write operations
- ⚠️ **Risk:** Invalid data reaches database

#### `options.includeSchema`
- ✅ **Set by:** User/caller (used in `save()`)
- ✅ **Effect:** Controls schema inclusion in child operations
- ⚠️ **Usage:** Not directly checked in controller

---

### ⚙️ Operation Config Flags (`coworker._config.operations[op]`)

#### `opConfig.draft`
- ✅ **Type:** `boolean`
- ✅ **Used by:** `execute()` to set `run_doc.options.draft`
- ❌ **Missing:** Defaults to `false`

#### `opConfig.type`
- ✅ **Values:** `"read" | "write" | "custom"`
- ✅ **Effect:** Routes execution path
- ❌ **Missing:** Defaults to `"custom"` (pass-through)

#### `opConfig.requiresSchema`
- ✅ **Type:** `boolean`
- ✅ **Effect:** Triggers schema fetch before operation
- ❌ **Error:** No schema fetched if doctype missing → validation may fail

#### `opConfig.validate`
- ✅ **Type:** `boolean`
- ✅ **Effect:** Enables `_validate()` for write operations
- ⚠️ **Override:** Bypassed by `options.skipValidation`

#### `opConfig.fetchOriginals`
- ✅ **Type:** `boolean`
- ✅ **Effect:** Fetches existing docs via `query.where` before write
- ❌ **Error:** Returns empty result if no matches found (not an error)
- ⚠️ **Merge:** Combines fetched + input for validation

---

### 🏗️ Schema-Level Flags

#### `schema.is_submittable`
- ✅ **Type:** `0 | 1`
- ✅ **Effect:** Enables docstatus workflow
- ⚠️ **AutoSave:** Only enforced when `is_submittable=1`

#### `schema._autosave`
- ✅ **Type:** `0 | 1` (default: `1`)
- ✅ **Effect:** Controls autosave for submittable docs
- ❌ **Blocked:** `autoSave()` exits if `_autosave=0`
- ❌ **Blocked:** `autoSave()` exits if `docstatus≠0`

---

### 🔒 Field-Level Flags

#### `field.reqd`
- ✅ **Type:** `0 | 1`
- ❌ **Error:** `validateField()` → "X is required" if value empty

#### `field.length`
- ✅ **Type:** `number`
- ❌ **Error:** `validateField()` → "X exceeds max length Y"

#### `field.min_value` / `field.max_value`
- ✅ **Type:** `number`
- ❌ **Error:** `validateField()` → "X minimum/maximum is Y"

#### `field.fieldtype`
- ✅ **Values:** `"Int" | "Float" | "Email" | "Date" | ...`
- ❌ **Error:** Type mismatch → "X must be valid Y"

---

### 🧾 Document-Level Flags

#### `doc.docstatus`
- ✅ **Values:** `0=Draft | 1=Submitted | 2=Cancelled`
- ❌ **Blocked:** `autoSave()` only works when `docstatus=0`

#### `doc.name`
- ✅ **Usage:** Determines create vs update in `save()`
- ⚠️ **New doc:** `!name` or `name.startsWith("new-")`

---

### 🔄 Internal Run Flags (State Tracking)

#### `run._saving`
- ✅ **Type:** `boolean`
- ❌ **Error:** `save()` called during save → "Save in progress"
- ✅ **Cleared:** After save completes/fails

#### `run._validationErrors`
- ✅ **Type:** `string[]`
- ✅ **Set by:** Failed `validate()`
- ✅ **Cleared:** On successful save

#### `run._saveError`
- ✅ **Type:** `string`
- ✅ **Set by:** Failed `save()`
- ✅ **Cleared:** On successful save

#### `run._items`
- ✅ **Type:** `Array`
- ✅ **Usage:** Caches fetched originals to avoid double-fetch

---

## ⚠️ COMMON ERROR SCENARIOS

1. **"Document not in draft mode"**
   - `save()` called when `options.draft=false`

2. **"Save in progress"**
   - `save()` called while `run._saving=true`

3. **AutoSave silent failure**
   - `draft=false` OR `_autosave=0` OR `docstatus≠0`

4. **Validation failures**
   - Missing required fields (`reqd=1`)
   - Type mismatches (`fieldtype` checks)
   - Length/range violations

5. **Missing schema**
   - `requiresSchema=true` but doctype undefined
   - `skipSchema=true` but validation enabled

6. **No doctype found**
   - `save()` called without `source_doctype` or `target_doctype`

┌─────────────────────────────────────────────────────────────────────┐
│ USER CALLS: execute(run_doc)                                         │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: options.draft === undefined?                                  │
│   YES → Set from opConfig.draft (default: false)                    │
│   NO  → Keep user-provided value                                     │
│ RESULT: options.draft = [true|false]                                 │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: options.skipController?                                       │
│   YES → ❌ EXIT: Call handler directly (skip all below)             │
│   NO  → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ GET: opConfig = coworker._config.operations[operation]               │
│ FLAGS LOADED:                                                        │
│   - opConfig.type           ["read"|"write"|"custom"]               │
│   - opConfig.requiresSchema [true|false]                             │
│   - opConfig.validate       [true|false]                             │
│   - opConfig.fetchOriginals [true|false]                             │
│   - opConfig.draft          [true|false] (already applied)           │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: opConfig.requiresSchema AND !options.skipSchema?              │
│   YES → Fetch schema for [source_doctype || target_doctype]         │
│         Load schema.fields[] with field flags:                       │
│           - field.reqd                                               │
│           - field.fieldtype                                          │
│           - field.length                                             │
│           - field.min_value                                          │
│           - field.max_value                                          │
│         Load schema flags:                                           │
│           - schema.is_submittable = 0                                │
│           - schema._autosave (not checked for is_submittable=0)      │
│   NO  → Skip schema fetch                                            │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ROUTE BY: opConfig.type                                              │
└─────────────────────────────────────────────────────────────────────┘
       ↓                       ↓                        ↓
   [READ]                  [WRITE]                  [CUSTOM]
       ↓                       ↓                        ↓
       │                       │                   ❌ EXIT: Pass to handler
       │                       │
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CHECK: options.skipValidation?          │
       │         │   YES → ❌ EXIT: Call handler directly  │
       │         │   NO  → Continue to _processWrite()     │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ GET: doctype = source_doctype ||        │
       │         │                target_doctype           │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CHECK: opConfig.fetchOriginals?         │
       │         │   YES → Fetch items via query.where     │
       │         │         Store in run._items             │
       │         │         CHECK: items.length === 0?      │
       │         │           YES → Return empty result     │
       │         │   NO  → Skip fetch                      │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CHECK: opConfig.validate?               │
       │         │   YES → For each item/input:            │
       │         │         Call _validate(merged, schema)  │
       │         │         For each field in schema:       │
       │         │           CHECK field.reqd              │
       │         │           CHECK field.fieldtype         │
       │         │           CHECK field.length            │
       │         │           CHECK field.min_value         │
       │         │           CHECK field.max_value         │
       │         │         IF errors → Return {success:false}│
       │         │   NO  → Skip validation                 │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CALL: handler with run._items if exists │
       │         └─────────────────────────────────────────┘
       │                       ↓
       ↓                       ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: handler (read operation)                                      │
│ RESULT: Get result.target.data[]                                    │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: Is Array(result.target.data) AND doctype exists?             │
│   YES → Call deserializeDocuments() (convert JSON strings)          │
│   NO  → Skip                                                         │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ✅ RETURN: result                                                    │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ USER CALLS: save(run)                                                │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run.options.draft?                                            │
│   NO  → ❌ ERROR: "Document not in draft mode"                      │
│   YES → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run._saving?                                                  │
│   YES → ❌ ERROR: "Save in progress"                                │
│   NO  → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: validate(run)                                                  │
│ For each field in schema.fields:                                    │
│   CHECK field.reqd                                                   │
│   CHECK field.fieldtype                                              │
│   CHECK field.length                                                 │
│   CHECK field.min_value                                              │
│   CHECK field.max_value                                              │
│ IF errors → Set run._validationErrors, render, return {success:false}│
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ MERGE: original + delta                                              │
│ CHECK: doc.name (is new?)                                            │
│   - Missing or starts with "new-" → CREATE                           │
│   - Otherwise → UPDATE                                               │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ SET: run._saving = true, render()                                    │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: run.child({                                                    │
│   operation: "create" or "update",                                   │
│   source_doctype: doctype,                                           │
│   target_doctype: doctype,                                           │
│   options: { includeSchema: false }                                  │
│ })                                                                   │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: saveRun.success?                                              │
│   YES → Update run.target.data, clear run.input                     │
│         DELETE run._saving, run._validationErrors                    │
│         Re-render, return {success:true}                             │
│   NO  → Set run._saveError, DELETE run._saving                      │
│         Render, return {success:false}                               │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ USER CALLS: autoSave(run)                                            │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run.options.draft?                                            │
│   NO  → ❌ SILENT EXIT                                               │
│   YES → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run._saving?                                                  │
│   YES → ❌ SILENT EXIT                                               │
│   NO  → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: schema.is_submittable === 1?                                  │
│   NO (= 0) → ⚠️ SKIP submittable checks, continue                   │
│   (For is_submittable=0: no _autosave or docstatus checks)          │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: isComplete(run) → validate(run)                                │
│ CHECK all field flags again                                          │
│ IF incomplete → render(), ❌ SILENT EXIT                             │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: save(run) (same flow as above)                                 │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│ USER CALLS: execute(run_doc)                                         │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: options.draft === undefined?                                  │
│   YES → Set from opConfig.draft (default: false)                    │
│   NO  → Keep user-provided value                                     │
│ RESULT: options.draft = [true|false]                                 │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: options.skipController?                                       │
│   YES → ❌ EXIT: Call handler directly (skip all below)             │
│   NO  → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ GET: opConfig = coworker._config.operations[operation]               │
│ FLAGS LOADED:                                                        │
│   - opConfig.type           ["read"|"write"|"custom"]               │
│   - opConfig.requiresSchema [true|false]                             │
│   - opConfig.validate       [true|false]                             │
│   - opConfig.fetchOriginals [true|false]                             │
│   - opConfig.draft          [true|false] (already applied)           │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: opConfig.requiresSchema AND !options.skipSchema?              │
│   YES → Fetch schema for [source_doctype || target_doctype]         │
│         Load schema.fields[] with field flags:                       │
│           - field.reqd                                               │
│           - field.fieldtype                                          │
│           - field.length                                             │
│           - field.min_value                                          │
│           - field.max_value                                          │
│         Load schema flags:                                           │
│           - schema.is_submittable = 1 ⭐                             │
│           - schema._autosave [0|1] (default: 1) ⭐                   │
│   NO  → Skip schema fetch                                            │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ROUTE BY: opConfig.type                                              │
└─────────────────────────────────────────────────────────────────────┘
       ↓                       ↓                        ↓
   [READ]                  [WRITE]                  [CUSTOM]
       ↓                       ↓                        ↓
       │                       │                   ❌ EXIT: Pass to handler
       │                       │
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CHECK: options.skipValidation?          │
       │         │   YES → ❌ EXIT: Call handler directly  │
       │         │   NO  → Continue to _processWrite()     │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ GET: doctype = source_doctype ||        │
       │         │                target_doctype           │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CHECK: opConfig.fetchOriginals?         │
       │         │   YES → Fetch items via query.where     │
       │         │         Store in run._items             │
       │         │         CHECK: items.length === 0?      │
       │         │           YES → Return empty result     │
       │         │   NO  → Skip fetch                      │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CHECK: opConfig.validate?               │
       │         │   YES → For each item/input:            │
       │         │         Call _validate(merged, schema)  │
       │         │         For each field in schema:       │
       │         │           CHECK field.reqd              │
       │         │           CHECK field.fieldtype         │
       │         │           CHECK field.length            │
       │         │           CHECK field.min_value         │
       │         │           CHECK field.max_value         │
       │         │         IF errors → Return {success:false}│
       │         │   NO  → Skip validation                 │
       │         └─────────────────────────────────────────┘
       │                       ↓
       │         ┌─────────────────────────────────────────┐
       │         │ CALL: handler with run._items if exists │
       │         └─────────────────────────────────────────┘
       │                       ↓
       ↓                       ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: handler (read operation)                                      │
│ RESULT: Get result.target.data[] (includes doc.docstatus)           │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: Is Array(result.target.data) AND doctype exists?             │
│   YES → Call deserializeDocuments() (convert JSON strings)          │
│   NO  → Skip                                                         │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ✅ RETURN: result (doc.docstatus available in data)                 │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ USER CALLS: save(run)                                                │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run.options.draft?                                            │
│   NO  → ❌ ERROR: "Document not in draft mode"                      │
│   YES → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run._saving?                                                  │
│   YES → ❌ ERROR: "Save in progress"                                │
│   NO  → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: validate(run)                                                  │
│ For each field in schema.fields:                                    │
│   CHECK field.reqd                                                   │
│   CHECK field.fieldtype                                              │
│   CHECK field.length                                                 │
│   CHECK field.min_value                                              │
│   CHECK field.max_value                                              │
│ IF errors → Set run._validationErrors, render, return {success:false}│
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ MERGE: original + delta                                              │
│ CHECK: doc.name (is new?)                                            │
│   - Missing or starts with "new-" → CREATE                           │
│   - Otherwise → UPDATE                                               │
│ ⭐ PRESERVE: merged.docstatus from original                          │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ SET: run._saving = true, render()                                    │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: run.child({                                                    │
│   operation: "create" or "update",                                   │
│   source_doctype: doctype,                                           │
│   target_doctype: doctype,                                           │
│   options: { includeSchema: false }                                  │
│ })                                                                   │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: saveRun.success?                                              │
│   YES → Update run.target.data (with doc.docstatus)                 │
│         Clear run.input                                              │
│         DELETE run._saving, run._validationErrors                    │
│         Re-render (UI may change based on docstatus), return success │
│   NO  → Set run._saveError, DELETE run._saving                      │
│         Render, return {success:false}                               │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ USER CALLS: autoSave(run)                                            │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run.options.draft?                                            │
│   NO  → ❌ SILENT EXIT                                               │
│   YES → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CHECK: run._saving?                                                  │
│   YES → ❌ SILENT EXIT                                               │
│   NO  → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ⭐ CHECK: schema.is_submittable === 1?                               │
│   YES → Continue to submittable-specific checks                      │
│   NO  → Skip to isComplete() check                                   │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ⭐ GET: schema._autosave (default: 1 if undefined)                   │
│ CHECK: _autosave === 0?                                              │
│   YES → ❌ BLOCKED: "AutoSave BLOCKED: _autosave=0"                 │
│         SILENT EXIT                                                  │
│   NO  → Continue                                                     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ⭐ CHECK: run.doc.docstatus !== 0?                                   │
│   YES → ❌ BLOCKED: "AutoSave BLOCKED: docstatus != 0"              │
│         SILENT EXIT (doc is submitted/cancelled)                     │
│   NO  → Continue (doc is in draft state)                             │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ CALL: isComplete(run) → validate(run)                                │
│ CHECK all field flags again:                                         │
│   - field.reqd                                                       │
│   - field.fieldtype                                                  │
│   - field.length                                                     │
│   - field.min_value                                                  │
│   - field.max_value                                                  │
│ IF incomplete → render(), ❌ SILENT EXIT                             │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│ ✅ "AutoSave proceeding to save()"                                   │
│ CALL: save(run) (same flow as above, preserves docstatus=0)         │
└─────────────────────────────────────────────────────────────────────┘

// User workflow:
1. Click "Edit" button
2. Modify form fields
3. Click "Save" button ← EXPLICIT ACTION REQUIRED
4. Data persists to DB

// Code behavior:
- No auto-save
- No continuous validation display
- save() will reject with error
- autoSave() silently exits

// User workflow:
1. Open form (already in edit mode)
2. Type in field → onChange fires
3. Field loses focus → autoSave() fires automatically
4. Data persists to DB (if complete)
5. No "Save" button needed*

// Code behavior:
- Continuous validation feedback
- Auto-save on field blur (if complete)
- save() available for manual trigger
- autoSave() actively monitors changes

*Save button may still exist for incomplete forms

async execute(run_doc) {
  // ✅ SINGLE SOURCE OF TRUTH
  if (options.draft === undefined) {
    const opConfig = coworker._config.operations[operation];
    run_doc.options.draft = opConfig?.draft ?? false;
  }
  // Now the ENTIRE execution tree knows the mode
}

coworker._config.operations = {
  "form:read": { 
    draft: true,  // Forms always start in draft mode
    type: "read"
  },
  "list:read": { 
    draft: false, // Lists are view-only
    type: "read" 
  },
  "create": { 
    draft: true,  // New docs need drafting
    type: "write" 
  }
}

async save(run) {
  // ❌ HARD STOP: Can't save if not in draft mode
  if (!run.options?.draft) {
    return {
      success: false,
      error: { message: "Document not in draft mode" }
    };
  }
  // ... validation and save logic
}

async autoSave(run) {
  // First check: Is draft mode enabled?
  if (!run.options?.draft) return; // ← Silent exit
  
  // Second check: Is save already in progress?
  if (run._saving) return;
  
  // Third check: For submittable docs, additional rules
  if (schema.is_submittable === 1) {
    if (schema._autosave === 0) return; // ❌ Disabled
    if (run.doc.docstatus !== 0) return; // ❌ Not draft state
  }
  
  // Proceed to save
  if (this.isComplete(run)) {
    await this.save(run);
  }
}

// ============================================================
// USE CASE 1: Submittable Document (is_submittable = 1)
// ============================================================

// Schema definition
{
  _schema_doctype: "Sales Invoice",
  is_submittable: 1,      // Has workflow states
  _autosave: 1,           // Auto-save enabled (default)
  fields: [...]
}

// User opens invoice "INV-2025-001" (docstatus=0, draft state)
const run = await coworker.run({
  operation: "form:read",  // ← Config has draft: true
  source_doctype: "Sales Invoice",
  query: { where: { name: "INV-2025-001" } }
});

// options.draft = true (from operation config)
// Document loaded with docstatus = 0

// User types in "customer_name" field
run.input = { customer_name: "ACME Corp" };

// onChange handler triggers:
await coworker.controller.autoSave(run);
// ✅ Checks pass:
//    - draft = true
//    - _saving = false
//    - is_submittable = 1
//    - _autosave = 1 ✅
//    - docstatus = 0 ✅
// → Saves to DB automatically

// User clicks "Submit" button
await coworker.run({
  operation: "submit",
  source_doctype: "Sales Invoice",
  query: { where: { name: "INV-2025-001" } }
});
// Document now has docstatus = 1 (submitted)

// User tries to edit again
run.input = { customer_name: "New Name" };
await coworker.controller.autoSave(run);
// ❌ BLOCKED: "docstatus != 0"
// → No auto-save (submitted docs are locked)

// Every handler needs to decide:
if (operation === "form:read") {
  // Should I allow auto-save?
  // Should I track changes?
  // What about validation?
}

// Result: Logic scattered everywhere, inconsistent behavior

// Controller decides ONCE at entry point
// All downstream code just checks: if (run.options.draft)
// Result: Consistent behavior, single source of truth

// Valid combinations:
{ draft: true,  docstatus: 0 } // ← Draft mode, draft state (auto-save ✅)
{ draft: true,  docstatus: 1 } // ← Draft mode, submitted (auto-save ❌)
{ draft: false, docstatus: 0 } // ← View mode, draft state
{ draft: false, docstatus: 1 } // ← View mode, submitted

// WRONG assumption:
options.draft === (is_submittable === 0 && docstatus === 0 && _autosave === 1)

draft: true  → Form allows edits, tracks changes, can call save()
draft: false → Form is read-only or requires explicit Save button

is_submittable: 0 → Simple doc (no workflow, no docstatus)
is_submittable: 1 → Workflow doc (Draft→Submitted→Cancelled)

docstatus: 0 → Draft (editable)
docstatus: 1 → Submitted (locked)
docstatus: 2 → Cancelled (archived)

_autosave: 0 → Disable auto-save (manual only)
_autosave: 1 → Enable auto-save (default)

// Schema
{
  _schema_doctype: "Note",
  is_submittable: 0,  // ← No workflow
  // docstatus doesn't exist
  // _autosave is ignored (only matters if is_submittable=1)
}

// Open form
const run = await coworker.run({
  operation: "form:read",  // draft: true
  source_doctype: "Note"
});

// Result:
options.draft = true     // ← From operation config
is_submittable = 0       // ← From schema
docstatus = undefined    // ← Doesn't exist
_autosave = undefined    // ← Not checked

// User types → autoSave() behavior:
✅ CHECK: draft = true
✅ CHECK: _saving = false
⚠️  SKIP: is_submittable check (= 0)
✅ → Saves immediately if complete

// Schema
{
  _schema_doctype: "Sales Invoice",
  is_submittable: 1,   // ← Has workflow
  _autosave: 1         // ← Auto-save enabled
}

// Case A: Draft mode, draft state
const run = await coworker.run({
  operation: "form:read",  // draft: true
  source_doctype: "Sales Invoice",
  query: { where: { name: "INV-001" } }
});

// Document data:
doc.docstatus = 0  // ← Draft state

// Result:
options.draft = true      // ← From operation
is_submittable = 1        // ← From schema
docstatus = 0             // ← From document
_autosave = 1             // ← From schema

// User types → autoSave() behavior:
✅ CHECK: draft = true
✅ CHECK: _saving = false
✅ CHECK: is_submittable = 1
✅ CHECK: _autosave = 1
✅ CHECK: docstatus = 0
✅ → Saves automatically

// ════════════════════════════════════════════

// Case B: Draft mode, submitted state
await coworker.run({
  operation: "submit",
  source_doctype: "Sales Invoice",
  query: { where: { name: "INV-001" } }
});

// NOW document is:
doc.docstatus = 1  // ← Submitted

// Result:
options.draft = true      // ← Still same
is_submittable = 1        // ← Still same
docstatus = 1             // ← CHANGED
_autosave = 1             // ← Still same

// User tries to edit → autoSave() behavior:
✅ CHECK: draft = true
✅ CHECK: _saving = false
✅ CHECK: is_submittable = 1
✅ CHECK: _autosave = 1
❌ CHECK: docstatus = 0  // FAILS (= 1)
❌ → BLOCKED: "AutoSave BLOCKED: docstatus != 0"

// Schema
{
  _schema_doctype: "Expense Claim",
  is_submittable: 1,
  _autosave: 0  // ← Disabled (sensitive financial doc)
}

// Open form
const run = await coworker.run({
  operation: "form:read",  // draft: true
  source_doctype: "Expense Claim"
});

// Document:
doc.docstatus = 0

// Result:
options.draft = true
is_submittable = 1
docstatus = 0
_autosave = 0  // ← KEY DIFFERENCE

// User types → autoSave() behavior:
✅ CHECK: draft = true
✅ CHECK: _saving = false
✅ CHECK: is_submittable = 1
❌ CHECK: _autosave = 1  // FAILS (= 0)
❌ → BLOCKED: "AutoSave BLOCKED: _autosave=0"

// But manual save still works:
await coworker.controller.save(run);
✅ → Saves successfully (draft=true allows it)

// Open list
const run = await coworker.run({
  operation: "list:read",  // draft: false ← KEY
  source_doctype: "Sales Invoice"
});

// Result:
options.draft = false     // ← From operation
is_submittable = 1        // ← From schema (irrelevant)
docstatus = varies        // ← Per document (irrelevant)
_autosave = 1             // ← From schema (irrelevant)

// User clicks inline edit → autoSave() behavior:
❌ CHECK: draft = false
❌ → SILENT EXIT (first check fails)

// User tries manual save:
await coworker.controller.save(run);
❌ → ERROR: "Document not in draft mode"

async autoSave(run) {
  // GATE 1: UI Mode (broadest)
  if (!run.options?.draft) return;
  // ↑ "Is the UI in editing mode?"
  
  // GATE 2: Concurrency
  if (run._saving) return;
  // ↑ "Is a save already happening?"
  
  // GATE 3: Schema Type (conditional)
  if (schema.is_submittable === 1) {
    // ↑ "Does this DocType have workflow?"
    
    // GATE 4: Schema Policy
    if (schema._autosave === 0) return;
    // ↑ "Is auto-save allowed for this DocType?"
    
    // GATE 5: Document State
    if (run.doc.docstatus !== 0) return;
    // ↑ "Is this document in draft state?"
  }
  
  // All gates passed → proceed
  if (this.isComplete(run)) {
    await this.save(run);
  }
}

// These are SEPARATE concerns:

options.draft        → "Can the UI save right now?"
is_submittable       → "Does this type have states?"
docstatus            → "What state is this doc in?"
_autosave            → "Is auto-save policy enabled?"

// They interact in autoSave():
if (!draft) exit;                    // UI not ready
if (is_submittable) {                // If workflow exists
  if (!_autosave) exit;              //   Check policy
  if (docstatus !== 0) exit;         //   Check state
}
save();                              // All checks passed

_autosave: 0  // Disabled - no auto-save
_autosave: 1  // Enabled - auto-save works (DEFAULT)

async autoSave(run) {
  if (!run.options?.draft) return;
  if (run._saving) return;

  const schema = run.target?.schema;

  if (schema?.is_submittable === 1) {
    // Get _autosave with default of 1
    const autosave = schema._autosave !== undefined ? schema._autosave : 1;

    // ✅ CHECK: Must be 1 (not 0)
    if (autosave === 0) {
      console.log("🚫 AutoSave BLOCKED: _autosave=0");
      return;
    }

    // ✅ CHECK: Must be draft state (not 1 or 2)
    if (run.doc?.docstatus !== 0) {
      console.log("🚫 AutoSave BLOCKED: docstatus != 0");
      return;
    }
  }

  if (!this.isComplete(run)) {
    coworker._render?.(run);
    return;
  }

  console.log("✅ AutoSave proceeding to save()");
  return await this.save(run);
}

// Current system has 4 flags doing overlapping work:
options.draft = true/false     // UI mode
is_submittable = 0/1          // Has workflow
_autosave = 0/1               // Auto-save policy
docstatus = 0/1/2             // Document state

// Instead of storing draft, calculate it:
function isDraftMode(schema, doc) {
  // Non-submittable docs are always "draft-able"
  if (schema.is_submittable === 0) return true;
  
  // Submittable docs: only draft if docstatus=0
  return doc.docstatus === 0;
}

// Auto-save logic becomes:
async autoSave(run) {
  if (run._saving) return;
  
  const schema = run.target?.schema;
  const doc = run.doc;
  
  // ✅ No draft flag needed
  if (schema.is_submittable === 1) {
    if (doc.docstatus !== 0) return;  // Not in draft state
    if (schema._autosave === 0) return;  // Policy blocks
  }
  
  if (this.isComplete(run)) {
    await this.save(run);
  }
}

async save(run) {
  // ❌ This check is redundant:
  if (!run.options?.draft) {
    return { success: false, error: "Document not in draft mode" };
  }
  
  // Because this already validates:
  if (schema.is_submittable === 1 && doc.docstatus !== 0) {
    return { success: false, error: "Cannot modify submitted document" };
  }
}

// Remove options.draft entirely
// Replace with:

function canSave(schema, doc) {
  if (!schema) return true;  // No schema = allow save
  if (schema.is_submittable === 0) return true;  // Simple docs always editable
  return doc.docstatus === 0;  // Workflow docs: only if draft
}

function canAutoSave(schema, doc) {
  if (!canSave(schema, doc)) return false;
  if (schema.is_submittable === 1 && schema._autosave === 0) return false;
  return true;
}

// Maybe draft controls "editing session" vs "document state"

// Example: Read-only views
const listView = await coworker.run({
  operation: "list:read",
  draft: false  // ← "Don't allow inline editing"
});
// Even if docstatus=0, user can't edit from list

// Example: Form views
const formView = await coworker.run({
  operation: "form:read",
  draft: true  // ← "This is an editing session"
});
// Now user CAN edit (if docstatus also allows)

// What draft SHOULD mean:
draft = "Is this UI component in edit mode?"
// (like contentEditable=true vs false)

// What it ACTUALLY does:
draft = "Gate-keeper for save() and autoSave()"
// (duplicates docstatus checks)

// Instead of:
{
  operation: "form:read",
  draft: true  // ← Redundant
}

// Just use:
{
  operation: "form:edit",  // ← Intent is clear
}

// Or:
{
  operation: "form:view",  // ← Read-only
}

async execute(run_doc) {
  const { operation } = run_doc;
  
  // ✅ Derive edit mode from operation
  const editOperations = ["form:edit", "create", "update"];
  const isEditMode = editOperations.includes(operation);
  
  // Remove draft flag entirely
}

async save(run) {
  // ❌ Remove this check:
  // if (!run.options?.draft) return error;
  
  // ✅ Only check document state:
  const schema = run.target?.schema;
  const doc = run.doc;
  
  if (schema?.is_submittable === 1 && doc.docstatus !== 0) {
    return { 
      success: false, 
      error: "Cannot save submitted/cancelled document" 
    };
  }
  
  // Proceed with save...
}

async autoSave(run) {
  if (run._saving) return;
  
  const schema = run.target?.schema;
  const doc = run.doc;
  
  // ✅ Just check the 3 essential flags:
  if (schema?.is_submittable === 1) {
    if (schema._autosave === 0) return;
    if (doc.docstatus !== 0) return;
  }
  
  if (this.isComplete(run)) {
    await this.save(run);
  }
}

// You have:
coworker._config.operations = {
  "update": {
    type: "write",
    requiresSchema: true,
    validate: true,
    fetchOriginals: true,
    draft: ???  // ← What should this be?
  }
}

// No separate operations like:
// - "form:edit" vs "form:view"
// - "inline:edit" vs "modal:edit"

// Scenario A: List view with inline editing
// - User clicks a cell
// - Types new value
// - Presses Enter
// - Should save immediately? Or need confirmation?

// Scenario B: Form view with draft mode
// - User opens form
// - Changes multiple fields
// - Auto-saves on blur
// - Can navigate away safely

// Scenario C: Dialog/Modal edit
// - User opens popup
// - Makes changes
// - Must click "Save" button
// - Cancel discards changes

// Controller becomes passive - no draft flag
coworker._config.operations = {
  "update": {
    type: "write",
    requiresSchema: true,
    validate: true,
    fetchOriginals: true
    // No draft flag
  }
}

// Caller decides when to save:
async save(run) {
  // ❌ Remove draft check - always allow save
  // Just validate document state
  const schema = run.target?.schema;
  const doc = run.doc;
  
  if (schema?.is_submittable === 1 && doc.docstatus !== 0) {
    return { success: false, error: "Cannot modify submitted doc" };
  }
  
  // Execute update
  return await coworker.run({
    operation: "update",
    source_doctype: run.source_doctype,
    input: { ...run.doc, ...run.input },
    query: { where: { name: doc.name } }
  });
}

// No autoSave() method - UI handles it
// List view: calls save() on Enter
// Form view: calls save() on blur
// Modal: calls save() on button click

// Operation config has no draft
coworker._config.operations = {
  "update": {
    type: "write",
    requiresSchema: true,
    validate: true,
    fetchOriginals: true
  }
}

// But individual runs can specify:
const formRun = await coworker.run({
  operation: "update",
  source_doctype: "Sales Invoice",
  query: { where: { name: "INV-001" } },
  options: { draft: true }  // ← Caller decides
});

// Now autoSave works:
await coworker.controller.autoSave(formRun);

// List view doesn't set draft:
const listRun = await coworker.run({
  operation: "update",
  source_doctype: "Sales Invoice",
  query: { where: { name: "INV-001" } }
  // No options.draft
});

// autoSave exits immediately:
await coworker.controller.autoSave(listRun);  // Silent exit

// Controller infers mode from how run was created
coworker._config.operations = {
  "update": {
    type: "write",
    requiresSchema: true,
    validate: true,
    fetchOriginals: true
  }
}

// Runs track their creation context:
const run = await coworker.run({
  operation: "update",
  source_doctype: "Sales Invoice",
  query: { where: { name: "INV-001" } },
  _context: "form"  // or "list", "modal"
});

// autoSave checks context:
async autoSave(run) {
  // Only auto-save in form context
  if (run._context !== "form") return;
  
  if (run._saving) return;
  
  const schema = run.target?.schema;
  const doc = run.doc;
  
  if (schema?.is_submittable === 1) {
    if (schema._autosave === 0) return;
    if (doc.docstatus !== 0) return;
  }
  
  if (this.isComplete(run)) {
    await this.save(run);
  }
}

// ============================================================
// CONTROLLER: Simple, no modes
// ============================================================

coworker.controller = {
  async execute(run_doc) {
    const { operation, options = {} } = run_doc;
    
    // No draft flag processing
    if (options.skipController) {
      return await coworker._handlers[operation](run_doc);
    }
    
    const opConfig = coworker._config.operations[operation];
    
    // ... rest of logic (fetch schema, validate, etc)
  },
  
  async save(run) {
    // ✅ Only check document state, not UI mode
    const schema = run.target?.schema;
    const doc = run.doc || run.target?.data?.[0];
    
    if (schema?.is_submittable === 1 && doc?.docstatus !== 0) {
      return { 
        success: false, 
        error: "Cannot modify submitted document" 
      };
    }
    
    // Merge and save
    const original = run.target?.data?.[0] || {};
    const merged = { ...original, ...run.input };
    
    return await coworker.run({
      operation: "update",
      source_doctype: run.source_doctype,
      input: merged,
      query: { where: { name: merged.name } }
    });
  }
  
  // ❌ Remove autoSave() entirely - UI handles it
};

// ============================================================
// UI LAYER: Handles auto-save logic
// ============================================================

// Form component:
class FormView {
  constructor(run) {
    this.run = run;
    this.autoSaveEnabled = true;  // Form-level setting
  }
  
  onFieldBlur(fieldname, value) {
    this.run.input[fieldname] = value;
    
    if (this.autoSaveEnabled) {
      this.tryAutoSave();
    }
  }
  
  async tryAutoSave() {
    if (this.saving) return;
    
    const schema = this.run.target?.schema;
    const doc = this.run.doc;
    
    // Check submittable rules
    if (schema?.is_submittable === 1) {
      if (schema._autosave === 0) return;
      if (doc?.docstatus !== 0) return;
    }
    
    // Check completeness
    if (!this.isComplete()) return;
    
    // Save
    this.saving = true;
    await coworker.controller.save(this.run);
    this.saving = false;
  }
}

// List component:
class ListView {
  onCellEdit(docname, fieldname, value) {
    // Inline edit - save immediately (no draft mode)
    await coworker.run({
      operation: "update",
      source_doctype: this.doctype,
      input: { [fieldname]: value },
      query: { where: { name: docname } }
    });
  }
}